home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / UI & Events / Implementing a Focus Module < prev    next >
Encoding:
Text File  |  1995-11-07  |  2.8 KB  |  60 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Recipes
  2.  
  3. Implementing a Focus Module
  4. By The OpenDoc Design Team
  5. November, 1995
  6.  
  7.  
  8. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  9. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  10. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  11.  
  12.  
  13. Introduction
  14.  
  15. The OpenDoc Arbitrator can be extended by developers, to handle additional focus types, perhaps associated with some exotic peripheral device. The same mechanism can also be used to “patch” the arbitrator. See also Patching OpenDoc.
  16.  
  17. Note: Most developers should not need to extend or patch the arbitrator. Please think very carefully before doing so. 
  18.  
  19. A focus is simply an ISO standard string. CI Labs will presumably set up a process for registering new foci for public consumption. The OpenDoc APIs use tokenized forms of these strings (using ODSession::Tokenize()).
  20.  
  21. ODArbitrator maintains a dictionary of focus modules, with the tokenized focus as the key. The methods of ODArbitrator (like RequestFocusSet()) look up a focus module for each focus, and calls appropriate methods of the focus module.
  22.  
  23. To extend the Arbitrator, a developer must implement a subclass of ODFocusModule, and install it in the arbitrator.
  24.  
  25. Defining a Focus Module
  26.  
  27. ODFocusModule is a System Object Model™ (SOM) class, just like ODPart, and must be subclassed (in IDL). The subclass should have an Init<ClassName>  method, and should override the methods below.  The Init<ClassName> method should call InitFocusModule.
  28.  
  29.     ODBoolean IsFocusExclusive(in ODTypeToken focus);
  30.     void SetFocusOwnership(in ODTypeToken focus, in ODFrame frame);
  31.     void UnsetFocusOwnership(in ODTypeToken focus, in ODFrame frame);
  32.     void TransferFocusOwnership(in ODTypeToken focus, 
  33.                     in ODFrame transferringFrame,
  34.                     in ODFrame newOwner);
  35.     ODFrame AcquireFocusOwner(in ODTypeToken focus);
  36.     ODFocusOwnerIterator CreateOwnerIterator(in ODTypeToken focus);
  37.     ODBoolean BeginRelinquishFocus(in ODTypeToken focus,
  38.                         in ODFrame requestingFrame);
  39.     void CommitRelinquishFocus(in ODTypeToken focus,
  40.                     in ODFrame requestingFrame);
  41.     void AbortRelinquishFocus(in ODTypeToken focus,
  42.                     in ODFrame requestingFrame);
  43.  
  44. The class reference documentation describes the semantics of each method in detail, and the source code for OpenDoc's standard exclusive focus module is included with these recipes. See ExFocus.idl and ExFocus.cpp.
  45.  
  46. Installing a Focus Module
  47.  
  48. A focus module should be installed by calling  ODArbitrator::RegisterFocus:
  49.     
  50.    void RegisterFocus(in ODTypeToken focus,
  51.                          in ODFocusModule focusModule);
  52.  
  53. For example:
  54.  
  55.     const ODFocusType kFooFocus = "Foo"; 
  56.     ODTypeToken fooFocus = session->Tokenize(ev, kFooFocus);
  57.     ODMyFocusModule* myFocusModule = new MyFocusModule();
  58.     arbitrator->RegisterFocus(ev, fooFocus,  myFocusModule);
  59.  
  60. The installation could take place in a part's initialization method, or in a Shell Plug-In.